src/domain/errors/CasError.js (1)

18-18: ⚠️ Potential issue | 🔴 Critical

Error.captureStackTrace is V8-specific and will throw in non-V8 runtimes.

The project supports Deno and Web environments (via WebCryptoAdapter), where Error.captureStackTrace may not exist. This line is called unconditionally and will throw a TypeError at runtime in those environments.

Proposed fix

-    Error.captureStackTrace(this, this.constructor);
+    if (typeof Error.captureStackTrace === 'function') {
+      Error.captureStackTrace(this, this.constructor);
+    }

src/infrastructure/adapters/NodeCryptoAdapter.js (1)

33-39: ⚠️ Potential issue | 🟡 Minor

decryptBuffer skips #validateKey — inconsistent with encryptBuffer.

encryptBuffer (line 21) calls this.#validateKey(key), but decryptBuffer does not. Passing an invalid key here will surface a raw node:crypto error instead of a descriptive CasError with INVALID_KEY_TYPE / INVALID_KEY_LENGTH. This is pre-existing behavior, but since this PR is the comprehensive JSDoc pass touching these methods, it's a good time to address the gap.

🛡️ Proposed fix

   /** `@override` */
   decryptBuffer(buffer, key, meta) {
+    this.#validateKey(key);
     const nonce = Buffer.from(meta.nonce, 'base64');

src/domain/value-objects/Manifest.js (1)

22-37: ⚠️ Potential issue | 🟠 Major

Discarded ManifestSchema.parse() result causes the encrypted default to be silently lost.

ManifestSchema.parse(data) is called for validation only — the return value (which carries Zod defaults and transforms) is discarded. This matters because EncryptionSchema defines encrypted: z.boolean().default(true). If a caller passes encryption metadata without the encrypted field, the schema parse succeeds (applying the default), but { ...data.encryption } on line 29 copies the raw input, which lacks encrypted.

🐛 Proposed fix — use the parsed result

     try {
-      ManifestSchema.parse(data);
-      this.slug = data.slug;
-      this.filename = data.filename;
-      this.size = data.size;
-      this.chunks = data.chunks.map((c) => new Chunk(c));
-      this.encryption = data.encryption ? { ...data.encryption } : undefined;
+      const validated = ManifestSchema.parse(data);
+      this.slug = validated.slug;
+      this.filename = validated.filename;
+      this.size = validated.size;
+      this.chunks = validated.chunks.map((c) => new Chunk(c));
+      this.encryption = validated.encryption ? { ...validated.encryption } : undefined;
       Object.freeze(this);

src/infrastructure/adapters/WebCryptoAdapter.js (1)

109-113: ⚠️ Potential issue | 🟠 Major

finalize() will crash with a null tag if called before the encrypt generator completes.

finalTag is initialized to null (line 83) and only set after the one-shot encrypt completes (line 104). If finalize() is called prematurely, this.#buildMeta(nonce, null) → this.#toBase64(null) throws. BunCryptoAdapter guards against this with a streamFinalized flag — add the same guard here.

🛡️ Proposed fix

     const chunks = [];
     let finalTag = null;
+    let streamFinalized = false;

     const encrypt = async function* (source) {
       // ...
       finalTag = fullBuffer.slice(-tagLength);
+      streamFinalized = true;

       yield Buffer.from(ciphertext);
     };

     const finalize = () => {
+      if (!streamFinalized) {
+        throw new CasError(
+          'Cannot finalize before the encrypt stream is fully consumed',
+          'STREAM_NOT_CONSUMED',
+        );
+      }
       return this.#buildMeta(nonce, finalTag);
     };

index.js (1)

213-221: ⚠️ Potential issue | 🟠 Major

writeFileSync blocks the event loop — use writeFile (async) for a library API.

restoreFile is an async method, so callers expect it to be non-blocking. Using writeFileSync for potentially large restored files (10 MB+ per your benchmarks) will stall the event loop. Switch to the async fs.promises.writeFile.

Proposed fix

-import { createReadStream, writeFileSync } from 'node:fs';
+import { createReadStream } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
 import path from 'node:path';

   async restoreFile({ manifest, encryptionKey, outputPath }) {
     const service = await this.#getService();
     const { buffer, bytesWritten } = await service.restore({
       manifest,
       encryptionKey,
     });
-    writeFileSync(outputPath, buffer);
+    await writeFile(outputPath, buffer);
     return { bytesWritten };
   }

src/domain/services/CasService.js (1)

273-275: ⚠️ Potential issue | 🟡 Minor

restore skips the file:restored event for empty manifests.

When manifest.chunks.length === 0, the method returns early (line 274) without emitting file:restored. Consumers listening for this event to track all restore operations will miss empty-file restores, breaking the documented contract that file:restored fires once per restore.

Proposed fix

     if (manifest.chunks.length === 0) {
+      this.emit('file:restored', {
+        slug: manifest.slug, size: 0, chunkCount: 0,
+      });
       return { buffer: Buffer.alloc(0), bytesWritten: 0 };
     }